text.match_named_groups

Match this text against the specified regular expression, returning a map whose keys are the names of each named group in the regular expression, and values are the text that was matched to the corresponding group.

Attempts to match this entire text, as opposed to searching for a match.

Unnamed groups and their matching text are not included in the returned map (use instead text.match_groups() to extract these).

Match groups in a regular expression are defined by any parentheses that the regular expression contains, and the groups are ordered by the position of their opening parentheses. For example, the regular expression (X(Y))(Z) contains 3 matching groups, which are:

(X(Y))
(Y)
(Z)

Named groups are match groups in a regular expression for which a name is specified. The match groups in the above example ((X(Y))(Z)) could be assigned names in the following manner:

(?<x>X(?<y>Y))(?<z>Z)

This is an equivalent regular expression, but the text matched by each group can be referenced by the group's name.

Examples:

'XYZ'.match_named_groups('(?<x>X(?<y>Y))(?<z>Z)') returns ['x': 'XY', 'y': 'Y', 'z': 'Z'].
'XYZ'.match_named_groups('(?<x>X(Y))(Z)') returns ['x': 'XY'].
'johnsmith@chromaway.com'.match_groups('(?<user>[a-z]+)@(?<domain>[a-z]+[.][a-z]+)') returns ['user': 'johnsmith', 'domain': 'chromaway.com'].
'X'.match_named_groups('(?<x>X)|(?<y>Y)') returns ['x': 'X'].
'X'.match_named_groups('(?<x>X)(?<y>Y?)') returns ['x': 'X', 'y': ''].

Matched non-capturing groups (notated (?:X), where X is a regular expression) are supported, and are not included in the returned map. Named groups that match the empty string with the ? and * quantifiers are included in the returned map, but named groups within unmatched alternatives are not.

Parameters

regex — the regular expression to match against

Returns

a map<text, text> containing the match groups and their matching text obtained by matching this text to the given regular expression; or null if this text does not match the given regular expression

Throws

exception — if regex is not a valid regular expression

See Also

Since

0.14.13